home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / src / lib / include / rpc / RCS / clnt.h,v < prev    next >
Text File  |  1991-03-23  |  10KB  |  384 lines
  1. head     1.2;
  2. branch   ;
  3. access   ;
  4. symbols  ;
  5. locks    ; strict;
  6. comment  @ * @;
  7.  
  8.  
  9. 1.2
  10. date     91.03.23.18.02.25;  author mottsmth;  state Exp;
  11. branches ;
  12. next     1.1;
  13.  
  14. 1.1
  15. date     91.03.23.18.01.28;  author mottsmth;  state Exp;
  16. branches ;
  17. next     ;
  18.  
  19.  
  20. desc
  21. @@
  22.  
  23.  
  24. 1.2
  25. log
  26. @Added retry support in the case of EIO errors.
  27. Supported only for udp clients.
  28. @
  29. text
  30. @/* @@(#)clnt.h    1.1 87/11/04 3.9 RPCSRC */
  31. /*
  32.  * Sun RPC is a product of Sun Microsystems, Inc. and is provided for
  33.  * unrestricted use provided that this legend is included on all tape
  34.  * media and as a part of the software program in whole or part.  Users
  35.  * may copy or modify Sun RPC without charge, but are not authorized
  36.  * to license or distribute it to anyone else except as part of a product or
  37.  * program developed by the user.
  38.  * 
  39.  * SUN RPC IS PROVIDED AS IS WITH NO WARRANTIES OF ANY KIND INCLUDING THE
  40.  * WARRANTIES OF DESIGN, MERCHANTIBILITY AND FITNESS FOR A PARTICULAR
  41.  * PURPOSE, OR ARISING FROM A COURSE OF DEALING, USAGE OR TRADE PRACTICE.
  42.  * 
  43.  * Sun RPC is provided with no support and without any obligation on the
  44.  * part of Sun Microsystems, Inc. to assist in its use, correction,
  45.  * modification or enhancement.
  46.  * 
  47.  * SUN MICROSYSTEMS, INC. SHALL HAVE NO LIABILITY WITH RESPECT TO THE
  48.  * INFRINGEMENT OF COPYRIGHTS, TRADE SECRETS OR ANY PATENTS BY SUN RPC
  49.  * OR ANY PART THEREOF.
  50.  * 
  51.  * In no event will Sun Microsystems, Inc. be liable for any lost revenue
  52.  * or profits or other special, indirect and consequential damages, even if
  53.  * Sun has been advised of the possibility of such damages.
  54.  * 
  55.  * Sun Microsystems, Inc.
  56.  * 2550 Garcia Avenue
  57.  * Mountain View, California  94043
  58.  */
  59. /*    @@(#)clnt.h 1.30 87/07/14 SMI      */
  60.  
  61. /*
  62.  * clnt.h - Client side remote procedure call interface.
  63.  *
  64.  * Copyright (C) 1984, Sun Microsystems, Inc.
  65.  */
  66.  
  67. #ifndef _CLNT_
  68. #define _CLNT_
  69.  
  70. /*
  71.  * Rpc calls return an enum clnt_stat.  This should be looked at more,
  72.  * since each implementation is required to live with this (implementation
  73.  * independent) list of errors.
  74.  */
  75. enum clnt_stat {
  76.     RPC_SUCCESS=0,            /* call succeeded */
  77.     /*
  78.      * local errors
  79.      */
  80.     RPC_CANTENCODEARGS=1,        /* can't encode arguments */
  81.     RPC_CANTDECODERES=2,        /* can't decode results */
  82.     RPC_CANTSEND=3,            /* failure in sending call */
  83.     RPC_CANTRECV=4,            /* failure in receiving result */
  84.     RPC_TIMEDOUT=5,            /* call timed out */
  85.     /*
  86.      * remote errors
  87.      */
  88.     RPC_VERSMISMATCH=6,        /* rpc versions not compatible */
  89.     RPC_AUTHERROR=7,        /* authentication error */
  90.     RPC_PROGUNAVAIL=8,        /* program not available */
  91.     RPC_PROGVERSMISMATCH=9,        /* program version mismatched */
  92.     RPC_PROCUNAVAIL=10,        /* procedure unavailable */
  93.     RPC_CANTDECODEARGS=11,        /* decode arguments error */
  94.     RPC_SYSTEMERROR=12,        /* generic "other problem" */
  95.  
  96.     /*
  97.      * callrpc & clnt_create errors
  98.      */
  99.     RPC_UNKNOWNHOST=13,        /* unknown host name */
  100.     RPC_UNKNOWNPROTO=17,        /* unkown protocol */
  101.  
  102.     /*
  103.      * _ create errors
  104.      */
  105.     RPC_PMAPFAILURE=14,        /* the pmapper failed in its call */
  106.     RPC_PROGNOTREGISTERED=15,    /* remote program is not registered */
  107.     /*
  108.      * unspecified error
  109.      */
  110.     RPC_FAILED=16
  111. };
  112.  
  113.  
  114. /*
  115.  * Error info.
  116.  */
  117. struct rpc_err {
  118.     enum clnt_stat re_status;
  119.     union {
  120.         int RE_errno;        /* realated system error */
  121.         enum auth_stat RE_why;    /* why the auth error occurred */
  122.         struct {
  123.             u_long low;    /* lowest verion supported */
  124.             u_long high;    /* highest verion supported */
  125.         } RE_vers;
  126.         struct {        /* maybe meaningful if RPC_FAILED */
  127.             long s1;
  128.             long s2;
  129.         } RE_lb;        /* life boot & debugging only */
  130.     } ru;
  131. #define    re_errno    ru.RE_errno
  132. #define    re_why        ru.RE_why
  133. #define    re_vers        ru.RE_vers
  134. #define    re_lb        ru.RE_lb
  135. };
  136.  
  137.  
  138. /*
  139.  * Client rpc handle.
  140.  * Created by individual implementations, see e.g. rpc_udp.c.
  141.  * Client is responsible for initializing auth, see e.g. auth_none.c.
  142.  */
  143. typedef struct {
  144.     AUTH    *cl_auth;            /* authenticator */
  145.     struct clnt_ops {
  146.         enum clnt_stat    (*cl_call)();    /* call remote procedure */
  147.         void        (*cl_abort)();    /* abort a call */
  148.         void        (*cl_geterr)();    /* get specific error code */
  149.         bool_t        (*cl_freeres)(); /* frees results */
  150.         void        (*cl_destroy)();/* destroy this structure */
  151.         bool_t          (*cl_control)();/* the ioctl() of rpc */
  152.     } *cl_ops;
  153.     caddr_t            cl_private;    /* private stuff */
  154. } CLIENT;
  155.  
  156.  
  157. /*
  158.  * client side rpc interface ops
  159.  *
  160.  * Parameter types are:
  161.  *
  162.  */
  163.  
  164. /*
  165.  * enum clnt_stat
  166.  * CLNT_CALL(rh, proc, xargs, argsp, xres, resp, timeout)
  167.  *     CLIENT *rh;
  168.  *    u_long proc;
  169.  *    xdrproc_t xargs;
  170.  *    caddr_t argsp;
  171.  *    xdrproc_t xres;
  172.  *    caddr_t resp;
  173.  *    struct timeval timeout;
  174.  */
  175. #define    CLNT_CALL(rh, proc, xargs, argsp, xres, resp, secs)    \
  176.     ((*(rh)->cl_ops->cl_call)(rh, proc, xargs, argsp, xres, resp, secs))
  177. #define    clnt_call(rh, proc, xargs, argsp, xres, resp, secs)    \
  178.     ((*(rh)->cl_ops->cl_call)(rh, proc, xargs, argsp, xres, resp, secs))
  179.  
  180. /*
  181.  * void
  182.  * CLNT_ABORT(rh);
  183.  *     CLIENT *rh;
  184.  */
  185. #define    CLNT_ABORT(rh)    ((*(rh)->cl_ops->cl_abort)(rh))
  186. #define    clnt_abort(rh)    ((*(rh)->cl_ops->cl_abort)(rh))
  187.  
  188. /*
  189.  * struct rpc_err
  190.  * CLNT_GETERR(rh);
  191.  *     CLIENT *rh;
  192.  */
  193. #define    CLNT_GETERR(rh,errp)    ((*(rh)->cl_ops->cl_geterr)(rh, errp))
  194. #define    clnt_geterr(rh,errp)    ((*(rh)->cl_ops->cl_geterr)(rh, errp))
  195.  
  196.  
  197. /*
  198.  * bool_t
  199.  * CLNT_FREERES(rh, xres, resp);
  200.  *     CLIENT *rh;
  201.  *    xdrproc_t xres;
  202.  *    caddr_t resp;
  203.  */
  204. #define    CLNT_FREERES(rh,xres,resp) ((*(rh)->cl_ops->cl_freeres)(rh,xres,resp))
  205. #define    clnt_freeres(rh,xres,resp) ((*(rh)->cl_ops->cl_freeres)(rh,xres,resp))
  206.  
  207. /*
  208.  * bool_t
  209.  * CLNT_CONTROL(cl, request, info)
  210.  *      CLIENT *cl;
  211.  *      u_int request;
  212.  *      char *info;
  213.  */
  214. #define    CLNT_CONTROL(cl,rq,in) ((*(cl)->cl_ops->cl_control)(cl,rq,in))
  215. #define    clnt_control(cl,rq,in) ((*(cl)->cl_ops->cl_control)(cl,rq,in))
  216.  
  217. /*
  218.  * control operations that apply to both udp and tcp transports
  219.  */
  220. #define CLSET_TIMEOUT       1   /* set timeout (timeval) */
  221. #define CLGET_TIMEOUT       2   /* get timeout (timeval) */
  222. #define CLGET_SERVER_ADDR   3   /* get server's address (sockaddr) */
  223. /*
  224.  * udp only control operations
  225.  */
  226. #define CLSET_RETRY_TIMEOUT 4   /* set retry timeout (timeval) */
  227. #define CLGET_RETRY_TIMEOUT 5   /* get retry timeout (timeval) */
  228. #define CLSET_RETRY_COUNT   6   /* set retry count (int)       */
  229. #define CLGET_RETRY_COUNT   7   /* get retry count (int)       */
  230. #define CLSET_RETRY_DELAY   8   /* set retry delay in secs(int)*/
  231. #define CLGET_RETRY_DELAY   9   /* get retry delay in secs(int)*/
  232.  
  233. /*
  234.  * udp sockets only: allow I/O retries if an EIO error is detected.
  235.  * These values can be altered with a clnt_control call.
  236.  * No support was added on the server side.
  237.  */
  238. #define RETRYCOUNTDFL 0         /* max retries.(-1 == infinity)*/
  239. #define RETRYDELAYDFL 60        /* delay (secs) between retries*/
  240.  
  241. /*
  242.  * void
  243.  * CLNT_DESTROY(rh);
  244.  *     CLIENT *rh;
  245.  */
  246. #define    CLNT_DESTROY(rh)    ((*(rh)->cl_ops->cl_destroy)(rh))
  247. #define    clnt_destroy(rh)    ((*(rh)->cl_ops->cl_destroy)(rh))
  248.  
  249.  
  250. /*
  251.  * RPCTEST is a test program which is accessable on every rpc
  252.  * transport/port.  It is used for testing, performance evaluation,
  253.  * and network administration.
  254.  */
  255.  
  256. #define RPCTEST_PROGRAM        ((u_long)1)
  257. #define RPCTEST_VERSION        ((u_long)1)
  258. #define RPCTEST_NULL_PROC    ((u_long)2)
  259. #define RPCTEST_NULL_BATCH_PROC    ((u_long)3)
  260.  
  261. /*
  262.  * By convention, procedure 0 takes null arguments and returns them
  263.  */
  264.  
  265. #define NULLPROC ((u_long)0)
  266.  
  267. /*
  268.  * Below are the client handle creation routines for the various
  269.  * implementations of client side rpc.  They can return NULL if a 
  270.  * creation failure occurs.
  271.  */
  272.  
  273. /*
  274.  * Memory based rpc (for speed check and testing)
  275.  * CLIENT *
  276.  * clntraw_create(prog, vers)
  277.  *    u_long prog;
  278.  *    u_long vers;
  279.  */
  280. extern CLIENT *clntraw_create();
  281.  
  282.  
  283. /*
  284.  * Generic client creation routine. Supported protocols are "udp" and "tcp"
  285.  */
  286. extern CLIENT *
  287. clnt_create(/*host, prog, vers, prot*/); /*
  288.     char *host;     -- hostname
  289.     u_long prog;    -- program number
  290.     u_long vers;    -- version number
  291.     char *prot;    -- protocol
  292. */
  293.  
  294.     
  295.     
  296.  
  297. /*
  298.  * TCP based rpc
  299.  * CLIENT *
  300.  * clnttcp_create(raddr, prog, vers, sockp, sendsz, recvsz)
  301.  *    struct sockaddr_in *raddr;
  302.  *    u_long prog;
  303.  *    u_long version;
  304.  *    register int *sockp;
  305.  *    u_int sendsz;
  306.  *    u_int recvsz;
  307.  */
  308. extern CLIENT *clnttcp_create();
  309.  
  310. /*
  311.  * UDP based rpc.
  312.  * CLIENT *
  313.  * clntudp_create(raddr, program, version, wait, sockp)
  314.  *    struct sockaddr_in *raddr;
  315.  *    u_long program;
  316.  *    u_long version;
  317.  *    struct timeval wait;
  318.  *    int *sockp;
  319.  *
  320.  * Same as above, but you specify max packet sizes.
  321.  * CLIENT *
  322.  * clntudp_bufcreate(raddr, program, version, wait, sockp, sendsz, recvsz)
  323.  *    struct sockaddr_in *raddr;
  324.  *    u_long program;
  325.  *    u_long version;
  326.  *    struct timeval wait;
  327.  *    int *sockp;
  328.  *    u_int sendsz;
  329.  *    u_int recvsz;
  330.  */
  331. extern CLIENT *clntudp_create();
  332. extern CLIENT *clntudp_bufcreate();
  333.  
  334. /*
  335.  * Print why creation failed
  336.  */
  337. void clnt_pcreateerror(/* char *msg */);    /* stderr */
  338. char *clnt_spcreateerror(/* char *msg */);    /* string */
  339.  
  340. /*
  341.  * Like clnt_perror(), but is more verbose in its output
  342.  */ 
  343. void clnt_perrno(/* enum clnt_stat num */);    /* stderr */
  344.  
  345. /*
  346.  * Print an English error message, given the client error code
  347.  */
  348. void clnt_perror(/* CLIENT *clnt, char *msg */);     /* stderr */
  349. char *clnt_sperror(/* CLIENT *clnt, char *msg */);    /* string */
  350.  
  351. /* 
  352.  * If a creation fails, the following allows the user to figure out why.
  353.  */
  354. struct rpc_createerr {
  355.     enum clnt_stat cf_stat;
  356.     struct rpc_err cf_error; /* useful when cf_stat == RPC_PMAPFAILURE */
  357. };
  358.  
  359. extern struct rpc_createerr rpc_createerr;
  360.  
  361.  
  362.  
  363. /*
  364.  * Copy error message to buffer.
  365.  */
  366. char *clnt_sperrno(/* enum clnt_stat num */);    /* string */
  367.  
  368.  
  369.  
  370. #define UDPMSGSIZE    8800    /* rpc imposed limit on udp msg size */
  371. #define RPCSMALLMSGSIZE    400    /* a more reasonable packet size */
  372.  
  373. #endif /*!_CLNT_*/
  374. @
  375.  
  376.  
  377. 1.1
  378. log
  379. @Initial revision
  380. @
  381. text
  382. @d199 12
  383. @
  384.